Plotting API
UXarray provides a fully-fledged plotting API for visualizing unstructured grids.
This notebook introduces how to interact with plotting methods directly though UXarray data structures.
See also
This notebook acts as an introduction into using the UXarray plotting API. Please refer to the following notebooks in this chapter for a detailed overview of visualization techniques for different purposes (e.g. Grid Topology, Polygons).
UXarray Plotting API Design
Before looking into the plotting API details, let us have a look at the current snapshot of the API design from an Unified Modelling Language (UML)-like standpoint:
Key takeaways from this design are that:
UXarray supports multiple unstructured grid formats and represent them all in a unified manner as we mentioned multiple times before. This allows us to provide our visualization functionality for all those supported grid formats.
Each Uxarray data structure (i.e. Grid, UxDataset, UxDataArray) has its own
.plotaccessor to provide visualization functions in the user API.The visualization functionality through these
.plotaccessors use HoloViz packages’ plotting functions, wrapping them in a way to exploit all the information that comes from unstructured grids (e.g. connectivity) and provide our unstructured grids-specific functions in the most convenient way for the user.Gridadditionally provides conversion functions that generateSpatialPandas.GeoDataFrameas well asMatplotlib.PolyCollectionandMatplotlib.LineCollectiondata structures to be visualized in HoloViz packages and Matplotlib, respectively, at the user’s own convenience.
Now, we can look into technical details along with some code snippets.
Imports
import uxarray as ux
file_dir = "../../meshfiles/"
grid_filename = file_dir + "oQU480.grid.nc"
data_filename = file_dir + "oQU480.data.nc"
grid = ux.open_grid(grid_filename)
uxds = ux.open_dataset(grid_filename, data_filename)
Grid Plotting
For visualizing the topology (i.e. geometry) of an unstructured grid, plotting is done through a Grid Instance
grid.plot(title="Default Grid Plot")
You can call specific plotting routines through the plot accessor
grid.plot.nodes(title="Grid Node Plot")
If you have a UxDataset or UxDataArray, you can access the Grid through the uxgrid attribute.
uxds.uxgrid.plot(title="Default Grid Plot through uxgrid attribute")
UxDataset & UxDataArray Plotting
For visualizing data variables, plotting is done through a UxDataArray instance.
uxds["bottomDepth"].plot(title="Default UxDataArray Plot")
As was shown with a Grid, you can call specific plotting routines through the plot accessor
uxds["bottomDepth"].plot.points(title="UxDataArray Point Plot")
Plotting a UxDataset currently not supported
uxds.plot()
/home/runner/miniconda3/envs/cookbook-dev/lib/python3.10/site-packages/uxarray/plot/accessor.py:471: UserWarning: Plotting for UxDataset instances not yet supported. Did you mean to plot a data variable, i.e. uxds['data_variable'].plot()
warnings.warn(
Customization
UXarray’s plotting API is built around the Holoviews Python package. For details about customizing plots, expected parameters, and other features, you can refer to their documentation. Below are brief examples on how to customize plots.
Figure Size
grid.plot(width=500, height=250)
Creating Subplots
(
grid.plot(width=500, height=250, color="Black")
+ grid.plot(width=500, height=250, color="Blue")
+ grid.plot(width=500, height=250, color="Red")
+ grid.plot(width=500, height=250, color="Green")
).cols(2)
(
grid.plot(width=500, height=250, color="Black")
+ grid.plot(width=500, height=250, color="Blue")
+ grid.plot(width=500, height=250, color="Red")
+ grid.plot(width=500, height=250, color="Green")
).cols(1)